Skip to content

feat: integrate l9-github-defaults v2.0.1 — governance kernels, seeding, canonical docs - #17

Merged
cryptoxdog merged 2 commits into
mainfrom
feat/org-defaults
Jul 29, 2026
Merged

feat: integrate l9-github-defaults v2.0.1 — governance kernels, seeding, canonical docs#17
cryptoxdog merged 2 commits into
mainfrom
feat/org-defaults

Conversation

@cryptoxdog

Copy link
Copy Markdown
Contributor

Problem

Governance logic in this org is duplicated per-repo and drifts (docs/AUDIT.md, 5 findings). There was no single canonical source for reusable PR/issue governance kernels, no seeding mechanism for the two non-inheritable files (CODEOWNERS, workflow caller), and community health files carried stale clone-based setup instructions.

Fix

Integrate l9-github-defaults v2.0.1 (14/15 files sha256-verified against MANIFEST.json; the manifest self-hash is definitionally unverifiable):

  • Kernels.github/workflows/governance-pr.yml + governance-issue.yml (workflow_call, consumed via templates/governance-caller.yml pinned @v1)
  • Seeding.github/workflows/seed-governance.yml (workflow_dispatch, dry-run default, gated by the governance-distribution environment — created on this repo during integration) for the two non-inheritable files
  • Templatesgovernance-caller.yml, CODEOWNERS.repo (slugs verified against live org: only platform exists; placeholders replaced with @Quantum-L9/platform + @cryptoxdog)
  • Scriptspreflight.sh (read-only assumption checks; 3 bugs fixed, see below), bootstrap.sh (idempotent, duplication-free)
  • Docsdocs/AUDIT.md, docs/DISTRIBUTION.md, root README.md
  • Merged, not replacedSECURITY.md (+canonical single-source clause, +out-of-scope), CONTRIBUTING.md (bootstrap-first setup per AUDIT finding 4, CANONICAL_LAW refs kept)

Deliberately not installed: pack CODEOWNERS (repo already has a canonical copy with real teams) and pack pull_request_template.md (PR #15 ships a superset; finding 1's nested-path fix satisfied there). ISSUE_TEMPLATE untouched (PR #16), per the pack's own guidance.

Upstream fixes applied:

  1. governance-issue.yml — replaced invalid ${{'{'}}…{{'}'}} expression-escaping with a plain JS priority map
  2. preflight.shset -e aborted the script after check 4 (probe loop); gh's colorized JSON broke every grep parse (org policy misread as unreadable, platform misreported as nonexistent); empty team read now treated as unverifiable

Risk

Low. All new workflows are workflow_call/workflow_dispatch only — nothing runs on push/PR events. Seed workflow defaults to dry-run and requires the governance-distribution environment. No existing file overwritten destructively; SECURITY/CONTRIBUTING changes are additive merges. Consuming repos untouched (out of scope).

Evidence

  • Pack integrity: 14/15 sha256 PASS (manifest self-hash N/A by construction)
  • YAML validation: all 4 workflow files parse, expected jobs present
  • bash -n clean on both scripts
  • preflight.sh end-to-end run (PAT, exit 0): platform OK · repo public OK · org Actions policy allowed_actions: all OK · all 38 consuming repos actions=on allowed=all · 1/39 repos already has a caller (L9-Ops-MCP) · 20+ repos hold local SECURITY.md/template overrides (future cleanup, out of scope)
  • governance-distribution environment created: 2026-07-28T19:25:57Z

After merge

  1. git tag v2.0.1 && git tag -f v1 v2.0.1 && git push origin v2.0.1 && git push -f origin v1 — callers reference @v1
  2. Add required reviewers to the governance-distribution environment (Settings → Environments)
  3. Create the GitHub App for seeding; set GOVERNANCE_APP_ID (variable) + GOVERNANCE_APP_PRIVATE_KEY (secret)
  4. Run Seed non-inheritable governance in dry-run, review, then seed

…eed automation, and canonical docs

- Add reusable governance kernels: governance-pr.yml, governance-issue.yml (workflow_call)
- Add seed-governance.yml (dry-run/seed) for non-inheritable files (CODEOWNERS, caller)
- Add templates/: governance-caller.yml (@v1 pinned) and CODEOWNERS.repo (real team slugs)
- Add scripts/: preflight.sh (read-only assumption checks), bootstrap.sh (idempotent, no duplication)
- Add docs/AUDIT.md (5 findings + evidence) and docs/DISTRIBUTION.md (inheritance vs seeding)
- Merge SECURITY.md: canonical single-source clause + out-of-scope section
- Merge CONTRIBUTING.md: bootstrap-first setup replacing clone-based step (AUDIT finding 4)
- Add root README.md documenting the defaults architecture
- Fix governance-issue.yml expression escaping; verify team slugs against live org (only 'platform' exists)
…t broke JSON parsing, treat empty team read as unverifiable

Verified end-to-end against the live org: exit 0, all 5 checks now report
(previously aborted after check 4 and misreported org policy as unreadable
and 'platform' as nonexistent).
@sonarqubecloud

Copy link
Copy Markdown

@cryptoxdog
cryptoxdog merged commit 100cee7 into main Jul 29, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant